Micron Document
welo git mirrors

Node / public / rns-proxy / files / README.md

Displaying Rendered • View raw • Download

README.md udp-support (6033dd61) Text, 4.60 KB

rns-proxy

│ Disclaimer: This project was created for academic and research purposes only. It is not
│ production-ready and should not be used in environments where stability, security, or reliability
│ are required.

SOCKS5 proxy that tunnels TCP connections over the Reticulum Network Stack. Route arbitrary TCP traffic through Reticulum's encrypted, delay-tolerant mesh network using the standard SOCKS5 protocol.

How it works

T282828
Te6edf3sequenceDiagram
Te6edf3participant Te6edf3App
Te6edf3participant Te6edf3Client Tff7b72as Te6edf3Client Tb4b4b4(Te6edf3SOCKS5 Tb4b4b4:T79c0ff1080Tb4b4b4)
Te6edf3participant Te6edf3RNS Tff7b72as Te6edf3Reticulum Te6edf3Network
Te6edf3participant Te6edf3Server Tff7b72as Te6edf3Server Tb4b4b4(Te6edf3exit Te6edf3nodeTb4b4b4)
Te6edf3participant Te6edf3Target Tff7b72as Te6edf3Target Te6edf3Host

Te6edf3AppTff7b72-Tff7b72>>Te6edf3ClientTb4b4b4: Te6edf3TCP Te6edf3CONNECT Tb4b4b4(Te6edf3SOCKS5Tb4b4b4)
Te6edf3ClientTff7b72-Tff7b72>>Te6edf3ClientTb4b4b4: Te6edf3SOCKS5 Te6edf3handshake Tff7b72+ Te6edf3allocate Te6edf3session_id

Te6edf3ClientTff7b72-Tff7b72>>Te6edf3RNSTb4b4b4: Te6edf3FrameTb4b4b4(Te6edf3CONNECTTb4b4b4, Te6edf3sidTb4b4b4, Te6edf3hostTb4b4b4:Te6edf3portTb4b4b4)
Te6edf3RNSTff7b72-Tff7b72>>Te6edf3ServerTb4b4b4: Te6edf3FrameTb4b4b4(Te6edf3CONNECTTb4b4b4, Te6edf3sidTb4b4b4, Te6edf3hostTb4b4b4:Te6edf3portTb4b4b4)
Te6edf3ServerTff7b72-Tff7b72>>Te6edf3TargetTb4b4b4: Te6edf3TcpStreamTb4b4b4:Tb4b4b4:Te6edf3connectTb4b4b4(Te6edf3hostTb4b4b4:Te6edf3portTb4b4b4)
Te6edf3TargetTff7b72-Tff7b72-Tff7b72>>Te6edf3ServerTb4b4b4: Te6edf3connected
Te6edf3ServerTff7b72-Tff7b72>>Te6edf3RNSTb4b4b4: Te6edf3FrameTb4b4b4(Te6edf3CONN_OKTb4b4b4, Te6edf3sidTb4b4b4)
Te6edf3RNSTff7b72-Tff7b72>>Te6edf3ClientTb4b4b4: Te6edf3FrameTb4b4b4(Te6edf3CONN_OKTb4b4b4, Te6edf3sidTb4b4b4)
Te6edf3ClientTff7b72-Tff7b72>>Te6edf3AppTb4b4b4: Te6edf3SOCKS5 Te6edf3success Te6edf3reply

Te6edf3loop Te6edf3Bidirectional Te6edf3relay
Te6edf3AppTff7b72-Tff7b72>>Te6edf3ClientTb4b4b4: Te6edf3TCP Te6edf3data
Te6edf3ClientTff7b72-Tff7b72>>Te6edf3RNSTb4b4b4: Te6edf3FrameTb4b4b4(Te6edf3DATATb4b4b4, Te6edf3sidTb4b4b4, Te6edf3payloadTb4b4b4)
Te6edf3RNSTff7b72-Tff7b72>>Te6edf3ServerTb4b4b4: Te6edf3FrameTb4b4b4(Te6edf3DATATb4b4b4, Te6edf3sidTb4b4b4, Te6edf3payloadTb4b4b4)
Te6edf3ServerTff7b72-Tff7b72>>Te6edf3TargetTb4b4b4: Te6edf3TCP Te6edf3write

Te6edf3TargetTff7b72-Tff7b72-Tff7b72>>Te6edf3ServerTb4b4b4: Te6edf3TCP Te6edf3data
Te6edf3ServerTff7b72-Tff7b72>>Te6edf3RNSTb4b4b4: Te6edf3FrameTb4b4b4(Te6edf3DATATb4b4b4, Te6edf3sidTb4b4b4, Te6edf3payloadTb4b4b4)
Te6edf3RNSTff7b72-Tff7b72-Tff7b72>>Te6edf3ClientTb4b4b4: Te6edf3FrameTb4b4b4(Te6edf3DATATb4b4b4, Te6edf3sidTb4b4b4, Te6edf3payloadTb4b4b4)
Te6edf3ClientTff7b72-Tff7b72-Tff7b72>>Te6edf3AppTb4b4b4: Te6edf3TCP Te6edf3write
Te6edf3end

Te6edf3Note Te6edf3over Te6edf3ClientTb4b4b4,Te6edf3ServerTb4b4b4: Te6edf3FrameTb4b4b4(Te6edf3CLOSETb4b4b4, Te6edf3sidTb4b4b4) Te6edf3ends Te6edf3the Te6edf3session


The project consists of two components:

• Server (exit node) -- registers on the RNS network, accepts incoming links, and proxies TCP connections to target hosts
• Client (local proxy) -- runs a local SOCKS5 server, multiplexes all connections through a single encrypted RNS link to the server

All TCP sessions are multiplexed over one RNS link using a custom binary frame protocol. Frames larger than T383838LINK_MDU are automatically chunked on send and reassembled on receive.

The client handles automatic reconnection when the link or underlying transport is lost, with exponential backoff and full RNS node recreation after repeated failures.

Build

Cargo

T282828
cargo build --release

Nix

T282828
nix build
T8b949e# or enter dev shell:
nix develop


Usage

Prerequisites

A running Reticulum daemon (T383838rnsd). Install via T383838pip install rns.

T282828
rnsd
T8b949e# or use the included example config:
./examples/run_rnsd.sh


Start the server

On the exit node machine:

T282828
rns-proxy server
T8b949e# or with a custom identity file:
rns-proxy server --identity-file /path/to/identity


On first run the server generates a new identity and saves it to T383838~/.reticulum/rns_proxy_identity. On subsequent runs it loads the same identity, so the destination hash stays the same.

T282828
Server started. Client address:
<32-hex-char-destination-hash>

Start the client

On the local machine:

T282828
rns-proxy client -d <hash-from-server>

The client starts a SOCKS5 proxy:

T282828
SOCKS5 ready: 127.0.0.1:1080

To make the proxy accessible from other devices on the network:

T282828
rns-proxy client -d <hash-from-server> -l T79c0ff0.0.0.0:1080


Use it

Configure any application to use T383838127.0.0.1:1080 as a SOCKS5 proxy:

T282828
curl --socks5 T79c0ff127.0.0.1:1080 https://example.com


CLI

T282828
rns-proxy [OPTIONS] <COMMAND>

Commands:
server Run the proxy server (exit node)
client Run the proxy client (local SOCKS5)

Options:
--debug Enable debug logging
-V, --version Print version
-h, --help Print help

Server options:

T282828
rns-proxy server [--identity-file <PATH>]

┌─────────────────┬─────────────────────────────────┬──────────────────────────────────────┐
│ Option │ Default │ Description │
├─────────────────┼─────────────────────────────────┼──────────────────────────────────────┤
│ T383838--identity-file │ T383838~/.reticulum/rns_proxy_identity │ Path to the persistent identity file │
└─────────────────┴─────────────────────────────────┴──────────────────────────────────────┘

Client options:

T282828
rns-proxy client -d <HASH> [-l 127.0.0.1:1080]

┌───────────────────┬────────────────┬─────────────────────────────┐
│ Option │ Default │ Description │
├───────────────────┼────────────────┼─────────────────────────────┤
│ T383838-d, T383838--destination │ required │ RNS destination hash (hex) │
│ T383838-l, T383838--listen │ T383838127.0.0.1:1080 │ Local SOCKS5 listen address │
└───────────────────┴────────────────┴─────────────────────────────┘

Protocol

Multiplexed frame format (wire-compatible with the Python implementation):

T282828
[1 byte type][4 bytes session_id][2 bytes payload_len][payload]

┌──────────┬──────┬───────────────────────────────────────────┐
│ Type │ Code │ Description │
├──────────┼──────┼───────────────────────────────────────────┤
│ CONNECT │ T3838380x01 │ Request connection to host:port │
│ CONN_OK │ T3838380x02 │ Connection succeeded │
│ CONN_ERR │ T3838380x03 │ Connection error (payload = UTF-8 reason) │
│ DATA │ T3838380x04 │ Bidirectional data │
│ CLOSE │ T3838380x05 │ Close session │
└──────────┴──────┴───────────────────────────────────────────┘

Served by rngit 1.4.2 - Generated in 0.04s